/*
 * @(#)ODPStorer.java	0.1 04/02/06
 *
 * Copyright 2006 Fabio Gasparetti. All rights reserved.
 */

package org.tabularium.text.se.odp;

import java.io.IOException;
import java.util.Iterator;

/**
 * 
 */
public interface ODPStorer {

	void add(ODPEntry e) throws ODPStorerException;

	// by id
	ODPEntry get(ODPEntry e) throws ODPStorerException;

	// by url
	ODPEntry get(String url) throws ODPStorerException;

	void remove(ODPEntry e) throws ODPStorerException;

	void remove(String url) throws ODPStorerException;

	/**
	 * Returns an iterator of ODPEntry objects.
	 */
	ODPEntryIterator browse() throws ODPStorerException;

	/**
	 * Returns an iterator of ODPEntry objects whose topics correspond to the given one or are included. 
	 */
	ODPEntryIterator browse(String topic) throws ODPStorerException;	

	/**
	 * Returns an array of ODPEntry objects.
	 */
	ODPEntry[] entries(String topic) throws ODPStorerException;	

	/**
	 * Returns the links of a given topic. 
	 */
	String[] links(String topic) throws ODPStorerException;

	/**
	 * Collects direct descendants of a given topic. 
	 * Returns an empty array if no child is available.
	 */
	String[] childs(String topic) throws ODPStorerException;

	/**
	 * Collects leafs given a tree root. 
	 */
	String[] leafs(String topic) throws ODPStorerException;

	/**
	 * An array of topics.
	 */
	String[] topics() throws ODPStorerException;

	/**
	 * Collects recursively topics under a given one.
	 */
	String[] topics(String topic) throws ODPStorerException;

	long size() throws ODPStorerException;

	void clear() throws ODPStorerException;
}
